package com.smart.community.complaint.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.PageResult;
import com.smart.community.complaint.dto.ComplaintDTO;
import com.smart.community.complaint.dto.ComplaintQueryDTO;
import com.smart.community.complaint.entity.Complaint;
import com.smart.community.complaint.vo.ComplaintVO;

import java.util.List;
import java.util.Map;

/**
 * 投诉建议服务接口
 * 
 * @author Wu.Liang
 * @version 1.0.0
 * @since 2025-06-26
 */
public interface IComplaintService extends IService<Complaint> {

    // ========================= 投诉提交查询接口 =========================

    /**
     * 提交投诉建议
     * 
     * @param complaintDTO 投诉信息
     * @return 投诉ID
     * @throws Exception 业务异常
     */
    Long submitComplaint(ComplaintDTO complaintDTO) throws Exception;

    /**
     * 分页查询投诉建议
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     * @throws Exception 业务异常
     */
    PageResult<ComplaintVO> pageComplaints(ComplaintQueryDTO queryDTO) throws Exception;

    /**
     * 获取投诉详情
     * 
     * @param complaintId 投诉ID
     * @return 投诉详情
     * @throws Exception 业务异常
     */
    ComplaintVO getComplaintDetail(Long complaintId) throws Exception;

    /**
     * 获取用户投诉列表
     * 
     * @param userId 用户ID
     * @return 投诉列表
     * @throws Exception 业务异常
     */
    List<ComplaintVO> getComplaintsByUserId(Long userId) throws Exception;

    // ========================= 投诉管理接口 =========================

    /**
     * 更新投诉信息
     * 
     * @param complaintId 投诉ID
     * @param complaintDTO 投诉信息
     * @return 更新结果
     * @throws Exception 业务异常
     */
    boolean updateComplaint(Long complaintId, ComplaintDTO complaintDTO) throws Exception;

    /**
     * 删除投诉记录
     * 
     * @param complaintId 投诉ID
     * @return 删除结果
     * @throws Exception 业务异常
     */
    boolean deleteComplaint(Long complaintId) throws Exception;

    // ========================= 投诉处理接口 =========================

    /**
     * 处理投诉
     * 
     * @param complaintId 投诉ID
     * @param complaintDTO 处理信息
     * @return 处理结果
     * @throws Exception 业务异常
     */
    boolean handleComplaint(Long complaintId, ComplaintDTO complaintDTO) throws Exception;

    /**
     * 分配投诉处理人
     * 
     * @param complaintId 投诉ID
     * @param handlerId 处理人ID
     * @return 分配结果
     * @throws Exception 业务异常
     */
    boolean assignHandler(Long complaintId, Long handlerId) throws Exception;

    /**
     * 解决投诉
     * 
     * @param complaintId 投诉ID
     * @param solution 解决方案
     * @return 解决结果
     * @throws Exception 业务异常
     */
    boolean solveComplaint(Long complaintId, String solution) throws Exception;

    /**
     * 关闭投诉
     * 
     * @param complaintId 投诉ID
     * @param remark 关闭备注
     * @return 关闭结果
     * @throws Exception 业务异常
     */
    boolean closeComplaint(Long complaintId, String remark) throws Exception;

    /**
     * 投诉重开
     * 
     * @param complaintId 投诉ID
     * @param reason 重开原因
     * @return 重开结果
     * @throws Exception 业务异常
     */
    boolean reopenComplaint(Long complaintId, String reason) throws Exception;

    /**
     * 回访投诉
     * 
     * @param complaintId 投诉ID
     * @param satisfactionRate 满意度评分
     * @param followupResult 回访结果
     * @return 回访结果
     * @throws Exception 业务异常
     */
    boolean followupComplaint(Long complaintId, Integer satisfactionRate, String followupResult) throws Exception;

    // ========================= 投诉统计接口 =========================

    /**
     * 获取投诉统计信息
     * 
     * @param communityId 社区ID
     * @return 统计信息
     * @throws Exception 业务异常
     */
    Map<String, Object> getComplaintStatistics(Long communityId) throws Exception;

    /**
     * 获取超时投诉列表
     * 
     * @return 超时投诉列表
     * @throws Exception 业务异常
     */
    List<ComplaintVO> getTimeoutComplaints() throws Exception;

    /**
     * 获取待回访投诉列表
     * 
     * @return 待回访投诉列表
     * @throws Exception 业务异常
     */
    List<ComplaintVO> getPendingFollowupComplaints() throws Exception;

    // ========================= 缓存管理接口 =========================

    /**
     * 清除投诉缓存
     * 
     * @param communityId 社区ID
     * @throws Exception 业务异常
     */
    void clearComplaintCache(Long communityId) throws Exception;
}
